Skip to content

docs: clarify that behavior when provided a nested sequence to asarray is unspecified #917

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from

Conversation

ev-br
Copy link
Member

@ev-br ev-br commented Mar 28, 2025

This came up in data-apis/array-api-strict#118.

AFAICS, the behavior of asarray([array, list]) does vary by implementation and is not explicitly mentioned in the standard. Thus add a note that it's unspecified.

Due diligence:

CuPy : allows sequences of arrays, does not allows mixed sequences of arrays/scalars:

In [2]: cp.asarray(cp.asarray([1, 2, 3]))
Out[2]: array([1, 2, 3])

In [3]: cp.asarray(cp.ones(3))
Out[3]: array([1., 1., 1.])

In [4]: cp.asarray([cp.ones(3), cp.ones(3)])
Out[4]: 
array([[1., 1., 1.],
       [1., 1., 1.]])

In [5]: cp.asarray([cp.ones(3), 1])
---------------------------------------------------------------------------
TypeError                                 Traceback (most recent call last)
..
TypeError: Implicit conversion to a NumPy array is not allowed. Please use `.get()` to construct a NumPy array explicitly.

In [6]: cp.asarray([cp.ones(3), [1, 2, 3]])
---------------------------------------------------------------------------
TypeError                                 Traceback (most recent call last)
..
TypeError: Implicit conversion to a NumPy array is not allowed. Please use `.get()` to construct a NumPy array explicitly.

Torch: does not allow sequences of tensors

In [1]: import torch

In [2]: torch.as_tensor(torch.ones(3))
Out[2]: tensor([1., 1., 1.])

In [3]: torch.as_tensor([torch.ones(3), torch.ones(3)])
---------------------------------------------------------------------------
ValueError                                Traceback (most recent call last)
Cell In[3], line 1
----> 1 torch.as_tensor([torch.ones(3), torch.ones(3)])

ValueError: only one element tensors can be converted to Python scalars

In [4]: torch.as_tensor([torch.ones(3), 1])
---------------------------------------------------------------------------
ValueError                                Traceback (most recent call last)
Cell In[4], line 1
----> 1 torch.as_tensor([torch.ones(3), 1])

ValueError: only one element tensors can be converted to Python scalars

In [5]: torch.as_tensor([torch.ones(3), [1, 2, 3]])
---------------------------------------------------------------------------
ValueError                                Traceback (most recent call last)
Cell In[5], line 1
----> 1 torch.as_tensor([torch.ones(3), [1, 2, 3]])

ValueError: only one element tensors can be converted to Python scalars

JAX : allows sequences but not scalars

In [1]: import jax.numpy as jnp

In [2]: jnp.asarray(jnp.ones(3))
Out[2]: Array([1., 1., 1.], dtype=float32)

In [3]: jnp.asarray([jnp.ones(3), jnp.ones(3)])
Out[3]: 
Array([[1., 1., 1.],
       [1., 1., 1.]], dtype=float32)

In [4]: jnp.asarray([jnp.ones(3), 1])
---------------------------------------------------------------------------
ValueError                                Traceback (most recent call last)
...
ValueError: All input arrays must have the same shape.

In [5]: jnp.asarray([jnp.ones(3), [1, 2, 3]])
Out[5]: 
Array([[1., 1., 1.],
       [1., 2., 3.]], dtype=float32)

Dask.array: as JAX.

Comment on lines +93 to +95
.. note::
If ``obj`` is a sequence with some elements being arrays, the behavior is unspecified and thus implementation-defined. Conforming
implentations may perform the conversion or raise an error.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
.. note::
If ``obj`` is a sequence with some elements being arrays, the behavior is unspecified and thus implementation-defined. Conforming
implentations may perform the conversion or raise an error.
.. note::
If ``obj`` is a sequence with some elements being arrays, the behavior is unspecified and thus implementation-defined. Conforming
implentations may perform the conversion or raise an error.
To join a sequence of arrays along a new axis, see :func:`~array_api.stack`.

@kgryte kgryte changed the title DOC: clarify that nested asarray is unspecified docs: clarify that behavior when provided a nested sequence to asarray is unspecified Mar 29, 2025
@kgryte kgryte added this to the v2025 milestone Mar 29, 2025
@kgryte kgryte added the topic: Creation Array creation. label Mar 29, 2025
ev-br added a commit to ev-br/scipy that referenced this pull request Apr 10, 2025
This to be forward compatible with data-apis/array-api#917
(planned for Array API spec 2025.12)
ev-br added a commit to ev-br/scipy that referenced this pull request Apr 10, 2025
This to be forward compatible with data-apis/array-api#917
(planned for Array API spec 2025.12)
ev-br added a commit to ev-br/scipy that referenced this pull request Apr 10, 2025
This to be forward compatible with data-apis/array-api#917
(planned for Array API spec 2025.12)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
topic: Creation Array creation.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants